home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1992 June: ROMin Holiday / ADC Developer CD (1992-06) (''ROMin Holiday'')_iso / Developer Connection - 06-1992.iso / Development Platforms / Apple II / Essentials / APW.ORCA.Cmds / Gregs.APW.Utils / Documentation / ToolLib < prev    next >
Encoding:
Text File  |  1990-07-19  |  10.3 KB  |  312 lines  |  [TEXT/pdos]
  1. ToolLib -- Library of routines useful when writing APW shell utilities
  2.  
  3. ToolLib is a library of routines that may be useful in your efforts to produce
  4. APW shell utilities.  There are four families of routines in the library -
  5. spinning cursor, error message management, class 1 string conversion, and
  6. keyboard scanning.  Each routine within each family will be described.
  7.  
  8.  
  9. Accessing the routines - Pascal
  10. -------------------------------
  11.  
  12. To access any of the library routines from within a Pascal program, you must
  13. first determine how your Pascal compiler is able to use any externally defined
  14. routines.  Usually this is done with the use of a 'Uses' statement.  A sample
  15. interface file is supplied in the PIncludes directory of the Libraries
  16. directory on the disk.  This file may need to be modified for use with your
  17. particular compiler.  (Since I don't normally use Pascal, I'll leave it up to
  18. you to set things up correctly.  After all, what d'ya expect for free???) ;-)
  19.  
  20.  
  21. Accessing the routines - C
  22. --------------------------
  23.  
  24. To access any of the library routines from within a C program, you must
  25. #include <ToolLib.h> to notify the compiler of the correct calling conventions
  26. for the routines.
  27.  
  28. When linking your program together, include '-lib 2/ToolLib' in your LinkIIGS
  29. command line.
  30.  
  31.  
  32. Spinning Cursor routines
  33. ========================
  34.  
  35. Five procedures in the library let you control the appearance and action of the
  36. spinning cursor.  The rotating bar says "I am currently processing."  These
  37. routines all use Pascal calling conventions and Pascal-style strings.
  38.  
  39.  
  40. The InitCursorCtl procedure
  41. ---------------------------
  42.  
  43. The InitCursorCtl procedure initializes the CursorCtl unit.  Call this
  44. procedure once prior to calling the RotateCursor or SpinCursor procedures
  45. described later.  Note that InitCursorCtl doesn't need to be called if you use
  46. only Hide_Cursor and Show_Cursor.  If RotateCursor or SpinCursor are called
  47. prior to InitCursorCtl being called, they will call InitCursorCtl themselves.
  48.  
  49. If the parameter 'delaycount' is 0, InitCursorCtl sets a default delaycount of
  50. 32.  This delaycount is used to determine when to update the rotating bar image
  51. on the screen.  The lower the number, the quicker the spin will be.  (The
  52. reason that the 'delaycount' parameter must be a 32-bit value is to make it
  53. easier to port MPW-style tools to the APW environment.  Under MPW, this value
  54. is a handle of an 'acur' resource, hence the 32-bit width.)
  55.  
  56. InitCursorCtl initializes data structures and variables, and then exits by
  57. calling Show_Cursor to display the first character in the rotating cursor
  58. sequence.
  59.  
  60. -> Pascal:
  61.     Procedure InitCursorCtl(delayCount : LongInt);
  62.  
  63. -> C:
  64.     pascal void InitCursorCtl(delayCount)
  65.     long    delayCount;
  66.  
  67.  
  68. The Show_Cursor procedure
  69. -------------------------
  70.  
  71. This function removes the default inverse space cursor from the screen and
  72. replaces it with the first frame of the animated cursor.  It then outputs a
  73. backspace so that any subsequent characters will automatically overwrite
  74. the cursor character.
  75.  
  76. -> Pascal:
  77.     Procedure Show_Cursor;
  78.  
  79. -> C:
  80.     pascal void Show_Cursor()
  81.  
  82.  
  83. The RotateCursor procedure
  84. --------------------------
  85.  
  86. RotateCursor is called to rotate the "I am active" "spinning wheel" cursor.
  87. The next cursor ("frame") is used when (counter MOD delaycount) (as
  88. specified in the InitCursorCtl call) = 0 (counter is some kind of
  89. incrementing or decrementing index maintained by the caller).  A positive
  90. counter sequences forward through the cursors (e.g., it rotates the cursor
  91. "clockwise"), and a negative cursor sequences through the cursors backwards
  92. (e.g., it rotates the cursor counterclockwise).
  93.  
  94. -> Pascal:
  95.     Procedure RotateCursor(Counter : LongInt);
  96.  
  97. -> C:
  98.     pascal void RotateCursor(counter)
  99.     unsigned long   counter;
  100.  
  101.  
  102. The SpinCursor procedure
  103. ------------------------
  104.  
  105. SpinCursor is similar in function to RotateCursor, except that instead of
  106. passing a counter, an increment is passed and added to a counter maintained
  107. within the CursorCtl unit itself. SpinCursor is provided for those users who
  108. do not happen to have a convenient counter handy but still want to use the
  109. spinning cursor.  A positive increment sequences forward through the cursors
  110. (rotating the cursor clockwise), and a negative increment sequences backward
  111. through the cursors (rotating the cursor counterclockwise).  A zero value for
  112. the increment resets the counter to zero. Note, it is the sign of the
  113. increment, and not the sign of the counter that determines the sequencing
  114. direction of the cursor (and hence the spin direction of the cursor).
  115.  
  116. -> Pascal:
  117.     Procedure SpinCursor(Increment : Integer);
  118.  
  119. -> C:
  120.     pascal void SpinCursor(increment)
  121.     unsigned short  increment;
  122.  
  123.  
  124. The Hide_Cursor procedure
  125. -------------------------
  126.  
  127. Hides the current character of the spinning cursor.  Use this routine when
  128. you wish to revert to the standard inverse space cursor.
  129.  
  130. -> Pascal:
  131.     Procedure Hide_Cursor;
  132.  
  133. -> C:
  134.     pascal void Hide_Cursor()
  135.  
  136.  
  137. Error Message File Manager
  138. ==========================
  139.  
  140. Three procedures in the library let you retrieve the text of error messages in
  141. the SysErrs file (located in the 4/ directory of your APW development
  142. environment).
  143.  
  144.  
  145. The InitErrMgr procedure
  146. ------------------------
  147.  
  148. Initializes the error manager.  If toolErrFilename is not null, this will
  149. open the resource fork of that file to allow access to tool-specific error
  150. messages.  If sysErrFilename is not null, this will open the resource fork
  151. of that file instead of the standard APW error message file. If
  152. showToolErrNbrs is TRUE, then any call to GetSysErrText will show the
  153. decimal and hexadecimal error number in parentheses after the text of the
  154. error message.  If this is false, all that GetSysErrText will provide is
  155. the text of the message.
  156.     
  157. To use the error manager, your tool must start up the Resource Manager
  158. prior to calling InitErrMgr.  This function will NOT do it for you.
  159.  
  160. -> Pascal:
  161.     Procedure InitErrMgr(toolErrFilename, sysErrFilename : Str255;
  162.                          showToolErrMbrs : Boolean);
  163.  
  164. -> C:
  165.     void InitErrMgr(toolErrFilename, sysErrFilename, showToolErrNbrs);
  166.     char    *toolErrFilename;
  167.     char    *sysErrFilename;
  168.     boolean showToolErrNbrs;
  169.  
  170.  
  171. The CloseErrMgr procedure
  172. -------------------------
  173. This simply closes any resources files opened by InitErrMgr.  It is not
  174. absolutely required that you call this function prior to exiting your tool,
  175. but it is available.  If it is not called, the Resource Manager will
  176. automatically close any files opened.  You must shutdown the Resource
  177. Manager yourself.
  178.  
  179. -> Pascal:
  180.     Procedure CloseErrMgr;
  181.  
  182. -> C:
  183.     extern void CloseErrMgr()
  184.  
  185.  
  186. The GetSysErrText procedure
  187. ---------------------------
  188.  
  189. GetSysErrText performs a resource lookup for the supplied errNbr.  It does
  190. this by calculating which resource number to use from the system resource
  191. file or the tool-specific error file.
  192.  
  193. The function places the error message text in the buffer pointed to by
  194. errMsg.  The C version also returns a pointer to a standard C string
  195. representing the error message associated with the given error number.  If
  196. there is message text available for the given error number, the string will
  197. have the following format:
  198.  
  199.     ### {tool name}: {message text}
  200.     
  201. If no specific message is available, the string will have the following
  202. format:
  203.  
  204.     ### {tool name}: Error {decimal error number} ($xxxx)
  205.  
  206. where $xxxx is the hexadecimal error code.
  207.  
  208. -> Pascal:
  209.     Procedure GetSysErrText(errNbr : Integer; errMsg : StringPtr);
  210.  
  211. -> C:
  212.     char *GetSysErrText(errNbr,errMsg)
  213.     unsigned    errNbr;
  214.     StringPtr   errMsg;
  215.  
  216.  
  217. GS/OS Class 1 string conversion procedures
  218. ==========================================
  219.  
  220. The library contains two routines that convert between GS/OS class 1 strings
  221. and C strings, and one routine use to convert slashes within a pathname to
  222. colons.  These will probably be more useful to C programmers, but they
  223. are also available to Pascal programmers who desire to use them.  These
  224. routines will only be known to the compiler if the file GSOS.h is included
  225. prior to including ToolLib.h (actually, the macro __GSOS__ must be defined
  226. prior to including ToolLib.h, to ensure that the type GSString255 has been
  227. defined).
  228.  
  229.  
  230. The c2gsstr procedure
  231. ---------------------
  232.  
  233. This function accepts a null terminated C string and copies it to a
  234. GS/OS-style string (length word followed by the characters of the string).
  235. On return, the function returns the pointer to the pathname structure.
  236.  
  237. -> C:
  238.     extern GSString255 *c2gsstr(str, pathGS)
  239.     char        *str;
  240.     GSString255 *pathGS;
  241.  
  242.  
  243. The gs2cstr procedure
  244. ---------------------
  245.  
  246. This function converts a GS/OS-style string (word length followed by the
  247. characters of the string) to a normal, null terminated C string.  On exit
  248. it returns a pointer to the string (which is the same as that specified
  249. on entry).
  250.  
  251. -> C:
  252.     extern char *gs2cstr(pathGS, str)
  253.     GSString255 pathGS;
  254.     char        *str;
  255.  
  256.  
  257. The colonize procedure
  258. ----------------------
  259.  
  260. Normalizes a filename string so that it contains only colons as pathname
  261. separators.  If there are no separators in the filename, the name is left
  262. unchanged.  If the filename contains no slashes, the filename is left
  263. unchanged.
  264.  
  265. -> C:
  266.     extern void colonize(fileName)
  267.     char    *fileName;
  268.  
  269.  
  270. Keyboard scanning routines
  271. ==========================
  272.  
  273. The keyboard scanning routines can be used to test for a Command-. keypress,
  274. and to automatically handle a spacebar press (used to pause the output of a
  275. utility).
  276.  
  277.  
  278. The pause function
  279. ------------------
  280.  
  281. This function should be called periodically by an APW tool to check for
  282. a pending keypress and/or command-. (abort signal).  If the command-.
  283. keypress is pending, the function will return a non-zero value
  284. (signifying TRUE).  If any other keypress is pending, the function
  285. will display an hourglass character on the screen and pause until
  286. another key is pressed.
  287.     
  288. The value returned is either non-zero (TRUE), indicating that command-.
  289. has been pressed and the tool should abort, or 0 (false), indicating
  290. that processing should proceed.
  291.  
  292. -> Pascal:
  293.     Function Pause : Boolean;
  294.  
  295. -> C:
  296.     extern int pause()
  297.  
  298.  
  299. The Wait function
  300. -----------------
  301.  
  302. This function operates similarly to the pause() function, except that
  303. it forces a keypress prior to returning to the caller.  That is, it
  304. waits in a loop until a keypress occurs.  The values returned are the 
  305. same as described for the pause() function.
  306.  
  307. -> Pascal:
  308.     Function Wait : Boolean;
  309.  
  310. -> C:
  311.     extern int wait()
  312.